t
Local Methods for Conditional Execution

*355*Local methods, however, do more than provide logical order, clarity, and design documentation within your methods. Locals*531* can have cases, and can serve an important purpose when used for conditional subtasks.

Return to the days in month method. As you recall, this method was based on a Prograph implementation of the logic in the “30 days has…” jingle. The fully elaborated version includes a final phase along these lines, “Except February which has 28 and 29 in leap years.” This phrase suggests that one of two responses is appropriate if the month is February.

In a traditional programming language, the February condition is handled by a syntactic structure such as an*431* IF/THEN/ELSE embedded within a*148* CASE OF or multiple condition ELSEIF clauses. In Prograph, you simply specify cases within a local method which is within the case of a method or of another local method.

u
Open the days in month method and Command-click the right case arrow twice to open the third case window of this method (Command-clicking opens the next case as it closes the current case). Perform an Opers to Local procedure on the "join" and string constant operations. Name the new local method leap year? to indicate that this operation determines whether February is 28 or 29 days long.

u
Open the leap year? local method, move the "join" and string constant operations to the side, and add the following “What year is it?” query and divisible-by-four test.

__________________________________________________________
NOTE:  The ÷ character is generated by typing Option-/. The aliases div and idiv, introduced in order to support international scripts, may be used instead of ÷ and ÷÷.
-----------------------------------------------------------

u
Copy the "join" and string constant operations to the clipboard. Option-click the right case arrow to add and open the second case. Paste the operations from the clipboard into the new case. Edit the string to " is 29 days long because it is leap year." and connect the required datalinks. Set a Breakpoint on the "join" in the second case of the leap year? local method.

u
Execute the month query method and respond February to the initial dialog. Enter 1992 at the year inquiry. At the Breakpoint, execution halts. Open the Stack window to confirm that month query called days in month, which dropped to its third case on the match with the February input. The third case in days in month executed its leap year? local method, which dropped to its second case.

Deeply nested*262* conditional forms are essential to traditional programming languages. Multicase-to-multicase method calls, multicase local methods, and locals within locals are essential features of Prograph. They allow you to specify the conditionally complex computations necessary for sophisticated applications.

A single method using nested locals can reasonably be viewed as an application within an application. The random from list method in the Chapter 6 Helpers file is an example that shows the use of local methods for both logical organization and conditional subtask processing.

u
Selectively load random from list in the Chapter 6 Helpers file to the Universal Methods window of your currently active environment.

u
Create a new universal method, item picker, which inputs a list constant, (one two three four), to random from list and displays the result with the show primitive. Next open the random from list method to inspect its inner workings. Your methods should look like this:

The innocent-looking single case of random from list provides a high-level view of a fairly complex computation. Seeing this method in action gives you a graphic example of the important function of nested, multicase local methods. Notice, too, how List and Loop annotations are used to allow a local to perform its processing on each item in a list or to process iteratively. What you see now, with regard to List and Loop annotations, are the kinds of things you will be doing in the later sections of the tutorial.

u
Select*1106* Trace in the Exec menu and open the*1001* Stack window. Then execute the item picker method.

u
Press Return time after time to execute each operation. With Trace on, every detail of the execution is visible, every local method is opened, and each operation within each local is individually executed. At any point, you can inspect the data and object values flowing along the datalinks. Before too long, you are three levels deep into the partition ranges local method. All pending execution*360* windows remain open until resolved, and the Stack window shows where you are.

__________________________________________________________
NOTE:  As you step through the random from list execution, notice how the editor and interpreter features work together to reveal what is going on. This is especially true when the author of the method has provided explanatory comments within the method and local-method case windows. Animation of the Stack and execution windows brings the method to life. The comments provide a running narrative of what is happening and why the computations are being performed.

As a new execution window opens, take a moment to read the author’s comments. Then as you step, operation by operation, through the method or local, open Value windows to confirm your understanding of the computations being performed.
---------------------------------------------------------

u
Continue to step through the execution of random from list. If you persevere, you can arrive at a full understanding of how this method works. If you get bogged down, simply Abort the execution and turn Trace mode off.

Stepping through the execution of random from list reveals the utility of local methods. Among the interesting things that were done using local methods within random from list was the use of*28* *515*List and*520* Loop annotations*533* on the roots and terminals of some of the*527* local methods. These annotations add yet another powerful means of getting Prograph to do elaborate computations with just a single operation icon.

==========================================================
TIP:  Option-clicking the*144* Case List Button of a case window of a local will open its parent local or method. Option-Command-clicking it will close the current window and open its parent.
=========================================================

t
List Multiplexes*746**748**749*

*208**513*List,*210* Loop,*587* and Repeat annotations turn a simple operation icon into a multiplex. If you think of simple operations as Prograph’s “mere mortals,” multiplexes are its “superhumans.” Adding List *517*or Loop *537*annotations to the roots and terminals of primitive, method, or local-method operations can turn a simple operation into a complex one. Such a multiplex operation can perform its computation on each item in a list or iteratively calculate until a halt condition is met. When*29* List and Loop *521*annotations*534* are used in combination, you can process items in a list at the same time that you iteratively calculate some value.

Start investigating multiplexes by List annotating a primitive.

u
Create a new universal method, multiplexing, in which you put a show operation with the input list, (1 2 3). Select both operations and replicate them. Drag the duplicates off to the side of the original operations.

u
Click the terminal of the second show operation and select*524* List from the*580**203* Controls*585* menu. The operation takes on the appearance of a stack of operation icons, which is the basic look of a Prograph multiplex. The terminal of show is also transformed into a List annotation, (…). Your method should look like this: 

u
Execute multiplexing to see the difference between showing a list and doing a list-annotated showing of the same list.

The resulting series of dialogs graphically demonstrates the effect of the *516*List annotation on a show operation. Unannotated, the show operation processes the list as a whole. List annotated, the show operation processes each item in the list. The List annotation does not have to know how many items are in the list, so the same multiplex*519* flexibly works on any length list.

_________________________________________________________
NOTE:  There is a convenient metaphor for understanding the list multiplex. An unannotated operation that is given a list as input works like a herd of cattle when the gate to their holding pen is flung open. They all rush out together and are exit-processed as a whole. Here the herd is the object. A List annotation, however, works like running the cows in the herd down a cattle chute. Each cow is acted upon individually, one at a time. Here, individual cows are the objects.
---------------------------------------------------------

If a single data value arrives at one terminal on an operation that has a List annotation of another of its terminals, the single data value is available each time the multiplex operates on an item in the list.

u
An unannotated show operation joins multiple inputs (in this case the list) before displaying the concatenated value in a dialog. So, double-click a new terminal with a string constant to the right of the current input of both of the show operations in multiplexing. Make the string input to the unannotated show be " is a list." and the string constant of the multiplex’s second input " is an item in a list." Be sure to type a space before the word “is” in both strings.

u
Execute multiplexing and note that the " is an item in a list." string is appended to each list item shown in a dialog when the List annotated show operation executes.
List annotations can also be applied to user-defined method operations.

u
Open the item picker method and List annotate the terminal of the random from list operation. Edit the string input to be a list of lists, ((one two)(three four)(five six)).

u
Think about the method and imagine what will happen when you execute it. Then execute item picker to see what happens.

The single dialog showing five or six is probably not what you expected. The show operation does not execute for each sublist processed by the multiplex. Only the last sublist item passes its selection to the show operation. The List multiplex processes items over and over within the multiplex operation, passing along output only when it is done processing. To achieve your design objectives, one of two alternative changes must be adopted.

o
If you want a series of separate dialogs to display the item selected from each sublist, modify the design of random from list. Bring the show operation inside of the random from list method and get rid of the terminal on the output bar. Delete the show operation and the root of the random from list operation in item picker.

o
An alternative is to List annotate the output root of the random from list operation in item picker.

List annotating a root of an operation performs an important function. In the current implementation of item picker, two executions of the random from list multiplex are computed with no outward result. A List annotation on a multiplex root creates a holding queue in which the output result of each execution is added to a list until all executions of the multiplex are done. The multiplex then unleashes the cumulative result of its computation in the form of a new list.

u
List annotate the root of random from list in item picker and execute the method.

A single dialog is displayed with a new list showing one item randomly selected from each of the three two-item lists that were input to random from list. List annotations can be applied to output roots of primitives as well as of simple and local methods.
___________________________________________________________
NOTE:  List annotations on basic mathematical, boolean, and input primitives can be very useful. To explore them, create a tester universal method and construct and execute such forms as these:

 

In each of these examples, the multiplex processes an input list and returns an output list. Create and execute some additional List annotation forms until you are confident that you understand Prograph’s list-processing behavior.
-----------------------------------------------------------

t
Loop Multiplexes*749*

*211**538*A second interesting form of root and terminal annotation is the Loop annotation.*540* Loop annotations*588* allow you to iteratively process until a halt condition is met. At loop termination, the values output are the values computed during the last successful*504* iteration.

___________________________________________________________
NOTE:  A convenient metaphor for understanding the loop multiplex is a railroad yard with a circular siding onto which a train can be routed and then let go at a flip of the yardmaster’s switch. Once a data value or object has been routed into a loop multiplex, it circles around within the loop until the switch is thrown, meaning the halt condition is met.

Like the train, a data value is either in the loop or out on the main track. No data passes out the root side of a Loop annotation*535* until the multiplex has completed its execution. When the halt condition is met, the switch is thrown and the root side of the Loop annotation functions just like an unannotated root passing its output data along any connected datalink. The value that passes out the Loop annotation root depends on whether the multiplex fails, terminates, or finishes, as you will see in the examples in the next section of the tutorial.
-----------------------------------------------------------

Prograph’s Loop annotation is similar to traditional programming language iterative constructs such as:*384**944**1161*

o FOR x TO y DO (z and x+1)

o WHILE condition DO statements

o REPEAT statements UNTIL condition

o LOOP (statements…
     including EXIT WHEN condition…
     statements)
 ENDLOOP

The syntax of most programming languages generally provides iterative forms that execute a specified number of times, or that test for an exit condition and then stop iterating. Prograph does this and then some. Prograph supports three primary ways to stop iterating—Terminate, Finish, and Fail.

__________________________________________________________
NOTE:  Loop annotations are generally applied to methods and local methods since an internal conditional test—which causes the current case to either terminate, finish, or fail—is used to end the looping. Prograph’s built-in primitives do not have such halt tests written into their function, so a solitary Loop annotation on primitives is not appropriate. 

A looping, unconditionally tested primitive can create such a “fast and closed” loop that you might find it difficult or impossible to break its execution. Only a system reset works in such cases. So be a bit careful when exploring Loop annotations.

You can, however, create user-defined primitives that have a halt condition test within their internal function. A Loop annotation on such a user-defined primitive does not suffer from the “unstoppability” of Prograph’s built-in primitives. 

A condition under which a Loop annotation on a primitive is both functional and useful is the mixed multiplex, in which a Loop and List annotation work together. You can explore mixed multiplexes in a later section of this tutorial. 
-----------------------------------------------------------

To explore the Loop annotation, make a method that iterates for a specified number of times.

u
Create a method, looper, and put a single operation, beeper, in its case window. Command-click to create a terminal on beeper then double-click on the terminal to set the newly attached constant operation to 10. Then click to select the terminal of beeper and choose Loop from the Controls menu. A transformation of the operation takes place.

___________________________________________________________
NOTE:  A Loop annotation always has a terminal and root that curve around on themselves, so to speak. If you Loop annotate a lone terminal or root, the Prograph editor turns the selected half of the Loop annotation and automatically creates the other side of the annotation. 

If the operation already has both roots and terminals when you apply a Loop annotation, the editor turns one of the opposite side roots or terminals into the other half of the annotation. Prograph makes its “best guess” as to which terminals and roots to match up when you apply Loop annotations. You can find additional information about how the selections are made and how you can control these selections in the Reference *937*manual. For the most part, as in these tutorial examples, the choice Prograph makes is the annotation you want.
----------------------------------------------------------

u
Double-click the left side of the beeper operation to create and open the case window of this new universal method. Edit the case window to appear as follows:

The conditional test that ends looper’s iteration of beeper is the Match operation looking for zero coming in on the input root. The Next Case control causes a drop to the second case of beeper when the input value is zero. The second case of beeper simply shows a That’s all, folks! message, at which point the Terminate control, activated on success of the show operation, halts the iteration.*586*

u
Execute looper.

You hear the ten beeps (squeals, clangs, or boinks, depending on your Control Panel sound setting) as expected. This is the most basic form of iteration in Prograph. To investigate further, try running looper with the Stack window open and Trace mode on.

This basic example uses the Terminate control to halt an iteration. As you will soon discover, Prograph also supports Finish, and Fail annotations to give you flexible control over when and how you exit iterations.